package com.yuno.mock.reader;

import com.yuno.mock.dto.ExcelReadRequest;
import com.yuno.mock.dto.ExcelReadResult;
import com.yuno.mock.strategy.ShardingStrategy;

import java.io.InputStream;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

/**
 * Excel读取器接口
 * 定义Excel文件读取的核心方法
 * 
 * @author xrm
 * @since 1.0.0
 */
public interface ExcelReader {
    
    /**
     * 同步读取Excel文件
     * 
     * @param request 读取请求参数
     * @return 读取结果
     * @throws Exception 读取异常
     */
    ExcelReadResult readExcel(ExcelReadRequest request) throws Exception;
    
    /**
     * 异步读取Excel文件
     * 
     * @param request 读取请求参数
     * @return 异步读取结果
     */
    CompletableFuture<ExcelReadResult> readExcelAsync(ExcelReadRequest request);
    
    /**
     * 多线程分片读取Excel文件
     * 
     * @param request 读取请求参数
     * @param shard 分片信息
     * @return 分片读取结果
     * @throws Exception 读取异常
     */
    ExcelReadResult readExcelShard(ExcelReadRequest request, ShardingStrategy.Shard shard) throws Exception;
    
    /**
     * 读取Excel文件的基本信息（不读取数据）
     * 
     * @param filePath 文件路径
     * @return 文件信息
     * @throws Exception 读取异常
     */
    Map<String, Object> getExcelInfo(String filePath) throws Exception;
    
    /**
     * 读取Excel文件的基本信息（从输入流）
     * 
     * @param inputStream 输入流
     * @param fileName 文件名
     * @return 文件信息
     * @throws Exception 读取异常
     */
    Map<String, Object> getExcelInfo(InputStream inputStream, String fileName) throws Exception;
    
    /**
     * 获取指定工作表的行数
     * 
     * @param filePath 文件路径
     * @param sheetName 工作表名称
     * @param sheetIndex 工作表索引
     * @return 行数
     * @throws Exception 读取异常
     */
    long getRowCount(String filePath, String sheetName, Integer sheetIndex) throws Exception;
    
    /**
     * 获取指定工作表的列数
     * 
     * @param filePath 文件路径
     * @param sheetName 工作表名称
     * @param sheetIndex 工作表索引
     * @return 列数
     * @throws Exception 读取异常
     */
    int getColumnCount(String filePath, String sheetName, Integer sheetIndex) throws Exception;
    
    /**
     * 验证Excel文件格式
     * 
     * @param filePath 文件路径
     * @return 是否为有效的Excel文件
     */
    boolean validateExcelFile(String filePath);
    
    /**
     * 验证Excel文件格式（从输入流）
     * 
     * @param inputStream 输入流
     * @param fileName 文件名
     * @return 是否为有效的Excel文件
     */
    boolean validateExcelFile(InputStream inputStream, String fileName);
    
    /**
     * 获取支持的文件扩展名
     * 
     * @return 支持的文件扩展名列表
     */
    List<String> getSupportedExtensions();
    
    /**
     * 获取读取器名称
     * 
     * @return 读取器名称
     */
    String getReaderName();
    
    /**
     * 检查是否支持指定的文件类型
     * 
     * @param fileName 文件名
     * @return 是否支持
     */
    boolean supports(String fileName);
}